---
title: "AppSession"
description: "The core class for interacting with user sessions"
---

## Overview

The `AppSession` class represents an active connection to a user's glasses session. It provides methods to:

- Subscribe to real-time events
- Display content on glasses
- Access hardware features
- Manage settings

## Properties

### Core Properties

```typescript
session.sessionId    // Unique session identifier
session.userId       // User's email address
session.capabilities // Hardware capabilities
session.isConnected  // Connection status
```

### Modules

```typescript
session.events      // Event handlers
session.layouts     // Display layouts
session.camera      // Camera access
session.audio       // Audio playback
session.location    // Location services
session.dashboard   // Dashboard control
session.settings    // App settings
```

## Event Handling

All event handlers use the `session.events` object:

```typescript
// Subscribe to events
session.events.onTranscription((data) => {
  console.log(`User said: ${data.text}`);
});

session.events.onButtonPress((data) => {
  console.log(`Button ${data.buttonId} pressed`);
});

session.events.onHeadPosition((data) => {
  console.log(`Head position: ${data.position}`);
});

// Connection events
session.events.onDisconnected(() => {
  console.log('Session disconnected');
});

session.events.onReconnected(() => {
  console.log('Session reconnected');
});
```

## Display Control

Show content on the glasses display:

```typescript
// Simple text
await session.layouts.showTextWall('Hello World!');

// Reference card
await session.layouts.showReferenceCard({
  title: 'Weather',
  text: '72°F and sunny'
});

// Double text wall
await session.layouts.showDoubleTextWall(
  'Top section',
  'Bottom section'
);

// Clear display
await session.layouts.clearView();
```

## Capabilities

Check what hardware is available:

```typescript
if (session.capabilities.hasCamera) {
  // Camera is available
}

if (session.capabilities.hasMicrophone) {
  // Microphone is available
}

if (session.capabilities.hasDisplay) {
  // Display is available
}
```

## Connection Management

The SDK handles connection management automatically:

- **Auto-reconnect**: Reconnects if connection drops
- **Grace period**: Apps have 20 seconds to reconnect
- **State preservation**: Session state survives reconnections

```typescript
// Check connection status
if (session.isConnected) {
  // Safe to send data
}

// Manual disconnect
session.disconnect();
```

## Best Practices

<AccordionGroup>
  <Accordion title="Always check capabilities">
    ```typescript
    if (session.capabilities.hasCamera) {
      const photo = await session.camera.requestPhoto();
    } else {
      // Fallback for devices without camera
    }
    ```
  </Accordion>
  
  <Accordion title="Handle disconnections gracefully">
    ```typescript
    session.events.onDisconnected(() => {
      // Save state
      // Show offline message
    });
    
    session.events.onReconnected(() => {
      // Restore state
      // Resume normal operation
    });
    ```
  </Accordion>
  
  <Accordion title="Use TypeScript for better development">
    ```typescript
    import { AppSession, TranscriptionData } from '@mentraos/sdk';
    
    function handleTranscription(
      session: AppSession,
      data: TranscriptionData
    ) {
      // TypeScript provides intellisense and type checking
    }
    ```
  </Accordion>
</AccordionGroup>

## Common Patterns

### Voice Commands

```typescript
session.events.onTranscription((data) => {
  const command = data.text.toLowerCase();
  
  if (command.includes('weather')) {
    showWeather(session);
  } else if (command.includes('time')) {
    showTime(session);
  }
});
```

### Button Navigation

```typescript
let menuIndex = 0;
const menuItems = ['Home', 'Settings', 'About'];

session.events.onButtonPress((data) => {
  if (data.buttonId === 'main' && data.pressType === 'short') {
    menuIndex = (menuIndex + 1) % menuItems.length;
    session.layouts.showTextWall(menuItems[menuIndex]);
  }
});
```

### Continuous Updates

```typescript
// Update display every 30 seconds
const interval = setInterval(async () => {
  if (session.isConnected) {
    const data = await fetchLatestData();
    await session.layouts.showReferenceCard({
      title: 'Live Data',
      text: data.value
    });
  }
}, 30000);

// Clean up on disconnect
session.events.onDisconnected(() => {
  clearInterval(interval);
});
```